<!DOCTYPE HTML>
<html lang="en">
<head>
<title>Input - Syntax &amp; Usage | AutoHotkey</title>
<meta name="description" content="The Input command waits for the user to type a string." />
<meta name="ahk:equiv-v2" content="commands/InputHook.htm" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>Input</h1>

<p>Waits for the user to type a string.</p>

<pre class="Syntax"><span class="func">Input</span> <span class="optional">, OutputVar, Options, EndKeys, MatchList</span></pre>
<h2>Parameters</h2>
<dl>

  <dt>OutputVar</dt>
  <dd><p>The name of the variable in which to store the text entered by the user (by default, artificial input is also captured).</p>
      <p>If this and the other parameters are omitted, any Input in progress in another <a href="../misc/Threads.htm">thread</a> is terminated and its <a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to the word NewInput. By contrast, the <a href="../misc/ErrorLevel.htm">ErrorLevel</a> of the current command will be set to 0 if it terminated a prior Input, or 1 if there was no prior Input to terminate.</p>
      <p><em>OutputVar</em> does not store keystrokes per se. Instead, it stores characters produced by keystrokes according to the active window's keyboard layout/language. Consequently, keystrokes that do not produce characters (such as <kbd>PageUp</kbd> and <kbd>Home</kbd>) are not stored (though they can be recognized via the <em>EndKeys</em> parameter below).</p>
      <p class="warning"><strong>Note:</strong> The <kbd>Escape</kbd> key is translated to the ASCII ESC character, <code>Chr(27)</code>. This can be avoided by including <code>{Esc}</code> in <em>EndKeys</em>, in which case pressing <kbd>Escape</kbd> will terminate Input.</p>
      <p>Whitespace characters such as <kbd>Tab</kbd> (`t) are stored literally. <kbd>Enter</kbd> is stored as linefeed (`n).</p></dd>

  <dt>Options</dt>
  <dd><p><u>A string of zero or more of the following letters (in any order, with optional spaces in between):</u></p>
      <p><strong>B</strong>: <kbd>Backspace</kbd> is ignored. Normally, pressing <kbd>Backspace</kbd> during an Input will remove the most recently pressed character from the end of the string. Note: If the input text is visible (such as in an editor) and the arrow keys or other means are used to navigate within it, <kbd>Backspace</kbd> will still remove the last character rather than the one behind the caret (insertion point).</p>
      <p><strong>C</strong>: Case sensitive. Normally, <em>MatchList</em> is not case sensitive (in versions prior to 1.0.43.03, only the letters A-Z are recognized as having varying case, not letters like &uuml;/&Uuml;).</p>
      <p><strong>I</strong>: Ignore input generated by the <a href="Send.htm#SendEvent">SendEvent</a> method if it has a <a href="SendLevel.htm">send level</a> of 0. However, the <a href="Send.htm#SendInput">SendInput</a> and <a href="Send.htm#SendPlay">SendPlay</a> methods are always ignored, regardless of this setting. <span class="ver">[v1.1.31+]:</span> The option letter can be followed by a number to set the minimum send level. <code>I</code> and <code>I1</code> are equivalent, and <code>I0</code> is the same as not specifying the option.</p>
      <p><strong>L</strong>: Length limit (e.g. <code>L5</code>). The maximum allowed length of the input. When the text reaches this length, the Input will be terminated and <a href="../misc/ErrorLevel.htm">ErrorLevel</a> will be set to the word Max unless the text matches one of the <em>MatchList</em> phrases, in which case <a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to the word Match. If unspecified, the length limit is 16383, which is also the absolute maximum in versions prior to <span class="ver">[v1.1.31]</span>.</p>
      <p><strong>M</strong>: Modified keystrokes such as <kbd>Control</kbd>+<kbd>A</kbd> through <kbd>Control</kbd>+<kbd>Z</kbd> are recognized and transcribed if they correspond to real ASCII characters. Consider this example, which recognizes <kbd>Control</kbd>+<kbd>C</kbd>:</p>
      <pre>CtrlC := Chr(3) <em>; Store the character for Ctrl-C in the CtrlC var.</em>
Input, OutputVar, L1 M
if (OutputVar = CtrlC)
    MsgBox, You pressed Control-C.
ExitApp</pre>
      <p class="note"><strong>Note</strong>: The characters <kbd>Ctrl</kbd>+<kbd>A</kbd> through <kbd>Ctrl</kbd>+<kbd>Z</kbd> correspond to <a href="Chr.htm">Chr(1)</a> through <a href="Chr.htm">Chr(26)</a>. Also, the <strong>M</strong> option might cause some keyboard shortcuts such as <kbd>Ctrl</kbd>+<kbd>&larr;</kbd> to misbehave while an Input is in progress.</p>
      <p><strong>T</strong>: Timeout (e.g. <code>T3</code>). The number of seconds to wait before terminating the Input and setting <a href="../misc/ErrorLevel.htm">ErrorLevel</a> to the word Timeout. If the Input times out, <em>OutputVar</em> will be set to whatever text the user had time to enter. This value can be a floating point number such as <code>2.5</code>.</p>
      <p id="vis"><strong>V</strong>: Visible. Normally, the user's input is blocked (hidden from the system). Use this option to have the user's keystrokes sent to the active window.</p>
      <p id="asterisk"><strong>*</strong>: Wildcard (find anywhere). Normally, what the user types must exactly match one of the <em>MatchList</em> phrases  for a match to occur. Use this option to find a match more often by searching the entire length of the input text.</p>
      <p id="E"><strong>E</strong> <span class="ver">[v1.1.20+]</span>: Handle single-character end keys by character code instead of by keycode. This provides more consistent results if the active window's keyboard layout is different to the script's keyboard layout. It also prevents key combinations which don't actually produce the given end characters from ending input; for example, if <code>@</code> is an end key, on the US layout <kbd>Shift</kbd>+<kbd>2</kbd> will trigger it but <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>2</kbd> will not (if the E option is used). If the <strong>C</strong> option is also used, the end character is case-sensitive.</p>
      </dd>

  <dt>EndKeys</dt>
  <dd><p>A list of zero or more keys, any one of which terminates the Input when pressed (the <em>EndKey</em> itself is not written to <em>OutputVar</em>). When an Input is terminated this way, <a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to the word EndKey followed by a colon and the name of the <em>EndKey</em>. Examples: <code>EndKey:.</code>, <code>EndKey:Escape</code>.</p>
      <p>The <em>EndKey</em> list uses a format similar to the <a href="Send.htm">Send</a> command. For example, specifying <code>{Enter}.{Esc}</code> would cause either <kbd>Enter</kbd>, <kbd>.</kbd>, or <kbd>Escape</kbd> to terminate the Input. To use the braces themselves as end keys, specify <code>{{}</code> and/or <code>{}}</code>.</p>
      <p>To use <kbd>Control</kbd>, <kbd>Alt</kbd>, or <kbd>Shift</kbd> as end-keys, specify the left and/or right version of the key, not the neutral version. For example, specify <code>{LControl}{RControl}</code> rather than <code>{Control}</code>.</p>
      <p><span class="ver">[v1.0.14+]</span>: Although modified keys such as <kbd>Alt</kbd>+<kbd>C</kbd> (!c) are not supported, certain characters that require the <kbd>Shift</kbd> key to be held down -- namely punctuation marks such as <code>?!:@&amp;{}</code> -- are supported. <span class="ver">[v1.1.20+]</span>: Other characters are supported with the <strong>E</strong> option described above. When the <strong>E</strong> and <strong>M</strong> options are both used, <kbd>Control</kbd>+<kbd>A</kbd> through <kbd>Control</kbd>+<kbd>Z</kbd> are supported by including the corresponding ASCII control characters in <em>EndKeys</em>.</p>
      <p>An explicit virtual key code such as <code>{vkFF}</code> may also be specified. This is useful in the rare case where a key has no name and produces no visible character when pressed. Its virtual key code can be determined by following the steps at the bottom fo the <a href="../KeyList.htm#SpecialKeys">key list page</a>.</p>
    </dd>

  <dt>MatchList</dt>
  <dd><p>A comma-separated list of key phrases, any of which will cause the Input to be terminated (in which case <a href="../misc/ErrorLevel.htm">ErrorLevel</a> will be set to the word Match). The entirety of what the user types must exactly match one of the phrases for a match to occur (unless the <a href="#asterisk">* option</a> is present). In addition, <strong>any spaces or tabs around the delimiting commas are significant</strong>, meaning that they are part of the match string. For example, if <em>MatchList</em> is <code>ABC , XYZ</code>, the user must type a space after ABC or before XYZ to cause a match.</p>
      <p>Two consecutive commas results in a single literal comma. For example, the following would produce a single literal comma at the end of string: <code>string1,,,string2</code>. Similarly, the following list contains only a single item with a literal comma inside it: <code>single,,item</code>.</p>
    <p>Because the items in <em>MatchList</em> are not treated as individual parameters, the list can be contained entirely within a variable. In fact, all or part of it must be contained in a variable if its length exceeds 16383 since that is the maximum length of any script line. For example, <em>MatchList</em> might consist of <code>%List1%,%List2%,%List3%</code> -- where each of the variables  contains a large sub-list of match phrases.</p>
    </dd>

</dl>

<h2>Error Handling</h2>
<p><span class="ver">[v1.1.04+]</span>: This command is able to throw an exception if called with no parameters and there is no Input in progress. For more information, see <a href="Catch.htm#RuntimeErrors">Runtime Errors</a>.</p>
<table class="info">
  <tr>
    <td style="width:15%"><p>1 or 0</p></td>
    <td><p>Whenever the command is used without parameters, <a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to 0 if it successfully terminates a prior input, or 1 if there is no Input in progress.</p></td>
  </tr>
  <tr>
    <td>NewInput</td>
    <td>The Input was interrupted by another <a href="../misc/Threads.htm">thread</a> that used the Input command.</td>
  </tr>
  <tr>
    <td>Max</td>
    <td>The Input reached the maximum allowed length and it does not match any of the items in <em>MatchList</em>.</td>
  </tr>
  <tr>
    <td>Timeout</td>
    <td>The Input timed out.</td>
  </tr>
  <tr>
    <td>Match</td>
    <td>The Input matches one of the items in <em>MatchList</em>.</td>
  </tr>
  <tr>
    <td>EndKey:<em>Name</em></td>
    <td>
      <p>One of the <em>EndKeys</em> was pressed to terminate the Input. In this case, <a href="../misc/ErrorLevel.htm">ErrorLevel</a> contains the word EndKey followed by a colon and the name of the terminating key without braces, e.g. <code>EndKey:Enter</code>, <code>EndKey:Escape</code>, etc.</p>
      <p>Note that <em>Name</em> is the "normalized" name of the key regardless of how it was written in <em>EndKeys</em>. For example, <code>{Esc}</code> and <code>{vk1B}</code> both produce <code>EndKey:Escape</code>. <a href="GetKey.htm">GetKeyName()</a> can be used to retrieve the normalized name.</p>
      <p>If the <a href="#E">E option</a> was used, <em>Name</em> is the actual character which was typed (if applicable). Otherwise, the key name is determined according to the script's active keyboard layout.</p>
      <p>Prior to <span class="ver">[v1.1.20]</span>, if the VK code of the end key was in the range 0x41 (A) through 0x5A (Z), ErrorLevel usually contained the corresponding ASCII character even if that wasn't correct for the current keyboard layout. In <span class="ver">[v1.1.20]</span> and later, the correct character is used. If a character in the range A through Z is used, it is upper-case for backward-compatibility; otherwise it is usually lower-case.</p>
    </td>
  </tr>
</table>

<h2 id="Remarks">Remarks</h2>
<p>If this command is used while an Input is  already in progress in another <a href="../misc/Threads.htm">thread</a>, that Input will be terminated and its <a href="../misc/ErrorLevel.htm">ErrorLevel</a> will be set to the word NewInput. After that (if parameters were given), the new Input will commence.</p>
<p>While an Input is in progress, new <a href="../misc/Threads.htm">threads</a> such as <a href="Menu.htm">custom menu items</a> and <a href="SetTimer.htm">timed subroutines</a> can still be created. Similarly, keyboard <a href="../Hotkeys.htm">hotkeys</a> are still in effect. However, hotkeys cannot be triggered by keys which the Input suppresses.</p>
<p>If the Input is not <a href="#vis">visible</a>, all keys are suppressed except the <a href="../KeyList.htm#modifier">standard modifier keys</a>, CapsLock, NumLock and ScrollLock. Even <em>EndKeys</em> and keystrokes which do not alter <em>OutputVar</em> are suppressed. For example, <kbd>Home</kbd> has no effect while <kbd>LWin</kbd>+<kbd>D</kbd> opens the Start menu (since <kbd>D</kbd> is suppressed but <kbd>LWin</kbd> is not).</p>
<p>When a script first uses this command, the <a href="_InstallKeybdHook.htm">keyboard hook</a> is installed (if it is not already). In addition, the script becomes <a href="_Persistent.htm">persistent</a>, meaning that <a href="ExitApp.htm">ExitApp</a> should be used to terminate it. The keyboard hook will stay installed until the next use of the <a href="Suspend.htm">Suspend</a> or <a href="Hotkey.htm">Hotkey</a> command, at which time it is removed if not required by any hotkeys or hotstrings.</p>
<p>If you use multiple languages or keyboard layouts, Input uses the keyboard layout of the active window rather than the script's (regardless of whether the Input is <a href="#vis">visible</a>). However, in versions prior to 1.0.44.03, the script's own layout is used.</p>
<p>Although not as flexible, <a href="../Hotstrings.htm">hotstrings</a> are generally easier to use than the Input command.</p>
<p><a href="InputHook.htm">InputHook()</a> is more flexible than the Input command.</p>

<h2>Related</h2>
<p><a href="KeyWait.htm">KeyWait</a>, <a href="../Hotstrings.htm">Hotstrings</a>, <a href="InputBox.htm">InputBox</a>, <a href="_InstallKeybdHook.htm">#InstallKeybdHook</a>, <a href="../misc/Threads.htm">Threads</a>, <a href="IfIn.htm">if var in/contains MatchList</a></p>
<h2>Examples</h2>
<div class="ex" id="ExAnyKey">
<p><a href="#ExAnyKey">#1</a>: Wait for the user to press any key. Keys that produce no visible character -- such as the modifier keys, function keys, and arrow keys -- are listed as end keys so that they will be detected too.</p>
<pre>Input, SingleKey, L1, {LControl}{RControl}{LAlt}{RAlt}{LShift}{RShift}{LWin}{RWin}{AppsKey}{F1}{F2}{F3}{F4}{F5}{F6}{F7}{F8}{F9}{F10}{F11}{F12}{Left}{Right}{Up}{Down}{Home}{End}{PgUp}{PgDn}{Del}{Ins}{BS}{CapsLock}{NumLock}{PrintScreen}{Pause}</pre>
</div>

<div class="ex" id="ExHotkey">
<p><a href="#ExHotkey">#2</a>: This is a working hotkey example. Since the hotkey has the tilde (~) prefix, its own keystroke will pass through to the active window. Thus, if you type <code>[btw</code> (or one of the other match phrases) in any editor, the script will automatically perform an action of your choice (such as replacing the typed text):</p>
<pre>~[::
Input, UserInput, V T5 L4 C, {enter}.{esc}{tab}, btw,otoh,fl,ahk,ca
if (ErrorLevel = "Max")
{
    MsgBox, You entered &quot;%UserInput%&quot;, which is the maximum length of text.
    return
}
if (ErrorLevel = "Timeout")
{
    MsgBox, You entered &quot;%UserInput%&quot; at which time the input timed out.
    return
}
if (ErrorLevel = "NewInput")
    return
If InStr(ErrorLevel, "EndKey:")
{
    MsgBox, You entered &quot;%UserInput%&quot; and terminated the input with %ErrorLevel%.
    return
}
<em>; Otherwise, a match was found.</em>
if (UserInput = "btw")
    Send, {backspace 4}by the way
else if (UserInput = "otoh")
    Send, {backspace 5}on the other hand
else if (UserInput = "fl")
    Send, {backspace 3}Florida
else if (UserInput = "ca")
    Send, {backspace 3}California
else if (UserInput = "ahk")
    Run, https://www.autohotkey.com
return
</pre>
<p>For an alternative version of this example, see <a href="Switch.htm#ExInput">Switch</a>.</p>
</div>

</body>
</html>
